(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI StrTrim Function
Deletes specific characters at both ends of a string.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function StrTrim(psz : LPSTR; pszTrimChars : LPCSTR) : BOOL;
Parameters
psz [in/out] Depending on which version of the function is called, a pointer to either a null-terminated, ANSI or Unicode buffer that contains the string, from which to remove the characters specified in pszTrimChars.
pszTrimChars [in] Pointer to, or address of, a null-terminated, ANSI or Unicode string that contains the characters to delete from the ends of the string specified in psz.
Return Values
The function returns TRUE (= 1) if it succeeded in deleting characters, specified in pszTrimChars, from the ends of the string, FALSE (= 0) otherwise.
Remarks
It is NOT possible to call the function with a Pascal string, typecast to a PChar (or PWideChar), as the first parameter (psz). This is because Pascal strings have a length "byte" (nowadays, actually a 32-bit value) and this is not updated by the called operating system functions when they remove characters, thereby shortening the string (see commented part at the top of the example code, below).
The comparison with the characters to delete is case-sensitive.
Unlike functions with similar names, the ShlWAPI function can be induced to remove arbitrary and not only "classic" white space characters from the ends of a string. However, it will not remove characters that are "shielded" by characters that were not specified in the pszTrimChars parameter. For example, if the input string were " AAA Hello Trimmed World BBB" (without the quotation marks) and the second parameter were "AB" (also without the quotation marks), the function would delete the Bs from the end but not the As from the beginning of the string. This is because the As are preceded by a blank and blanks were not specified in the list of characters to remove.
Example
PROCEDURE TForm4.TestShlWAPIStrTrim(Sender : TObject); VAR strtotrim : STRING; VAR strtotrimlen : INTEGER; VAR strtotrimbufp : POINTER; VAR charstotrim : STRING; VAR apiretval : BOOL; VAR newinfoline : STRING; BEGIN strtotrim := ''; strtotrimlen := 0; strtotrimbufp := NIL; charstotrim := ''; apiretval := FALSE; newinfoline := ''; //BEGIN The following code will cause an EAccessViolotion exception //strtotrim := ' ' + #9 + ' The quick, brown fox jumped over the fence ' + #9 + #13 + #10; //charstotrim := ' ' + #9 + #10 + #13 + ' '; //newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' //+ charstotrim; //Memo1.Lines.Add(newinfoline); //This code will cause an EAccessViolotion exception in the following line !!! //apiretval := StrTrim(PChar(strtotrim), PChar(charstotrim)); //IF apiretval = TRUE THEN //newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"' //ELSE //newinfoline := 'StrTrim returned FALSE !'; //Memo1.Lines.Add(newinfoline); //END The following code will cause an EAccessViolotion strtotrim := ' The quick, brown fox jumped over the fence '; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := ' ';//Remove blanks newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (blanks)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := ' ' + #9 + ' The quick, brown fox jumped over the fence ' + #9 + #13 + #10; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := ' ' + #9 + #10 + #13 + ' '; newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (blanks, tabs, carriage returns, and line feeds)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := ' ' + #9 + 'AA The quick, brown fox jumped over the fence BB' + #9 + #13 + #10; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := ' ' + #9 + #10 + #13 + 'AB'; newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (blanks, tabs, carriage returns, line feeds, A, and B)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := 'AA The quick, brown fox jumped over the fence BB '; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := 'aB'; newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (a and B)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := 'AA The quick, brown fox jumped over the fence BB '; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := 'Ab'; newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (A and b)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := 'The quick, brown fox jumped over the fence'; //Nothing to delete ! strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := ' ' + #9 + #10 + #13 + 'AB'; newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (blanks, tabs, carriage returns, line feeds, A, and B)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := ' ' + #9 + 'AA The quick, brown fox jumped over the fence BB' + #9 + #13 + #10; strtotrimlen := Length(strtotrim); strtotrimbufp := AllocMem(strtotrimlen + 1); Move(strtotrim[1], strtotrimbufp^, strtotrimlen); charstotrim := '';//No characters to delete specified newinfoline := 'StrTrim called with psz (without the quotation marks) = "' + strtotrim + '", pszTrimChars = ' + '"' + charstotrim + '" (No characters to delete specified !)'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, PChar(charstotrim)); IF apiretval = TRUE THEN BEGIN strtotrim := PChar(strtotrimbufp); newinfoline := 'StrTrim returned TRUE and "' + strtotrim + '"'; END ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); FreeMem(strtotrimbufp); strtotrim := ''; //Empty string strtotrimbufp := NIL; newinfoline := 'StrTrim called with psz = NIL, pszTrimChars = NIL'; Memo1.Lines.Add(newinfoline); apiretval := StrTrim(strtotrimbufp, NIL); IF apiretval = TRUE THEN newinfoline := 'StrTrim returned TRUE' ELSE newinfoline := 'StrTrim returned FALSE !'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;
When run, the above code essentially produces the output below (however, we have inserted line breaks into output for better legibility):
StrTrim called with psz (without the quotation marks) = " The quick, brown fox jumped over the fence ", pszTrimChars = " " (blanks) StrTrim returned TRUE and "The quick, brown fox jumped over the fence" StrTrim called with psz (without the quotation marks) = " The quick, brown fox jumped over the fence ", pszTrimChars = " " (blanks, tabs, carriage returns, and line feeds) StrTrim returned TRUE and "The quick, brown fox jumped over the fence" StrTrim called with psz (without the quotation marks) = " AA The quick, brown fox jumped over the fence BB ", pszTrimChars = " AB" (blanks, tabs, carriage returns, line feeds, A, and B) StrTrim returned TRUE and "The quick, brown fox jumped over the fence" StrTrim called with psz (without the quotation marks) = "AA The quick, brown fox jumped over the fence BB ", pszTrimChars = "aB" (a and B) StrTrim returned FALSE ! StrTrim called with psz (without the quotation marks) = "AA The quick, brown fox jumped over the fence BB ", pszTrimChars = "Ab" (A and b) StrTrim returned TRUE and " The quick, brown fox jumped over the fence BB " StrTrim called with psz (without the quotation marks) = "The quick, brown fox jumped over the fence", pszTrimChars = " AB" (blanks, tabs, carriage returns, line feeds, A, and B) StrTrim returned FALSE ! StrTrim called with psz (without the quotation marks) = " AA The quick, brown fox jumped over the fence BB ", pszTrimChars = "" (No characters to delete specified !) StrTrim returned FALSE ! StrTrim called with psz = NIL, pszTrimChars = NIL StrTrim returned FALSE !
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (StrTrim and StrTrimA) and Unicode (StrTrimW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.: 4.71
Min. ShlWAPI.dll version based on SST research: 4.71
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0
Min. OS version(s) according to SST research.: Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98, Windows 2000 and later
See Also
StrDup, SHStrDup.
 
Windows APIs: StrTrim, StrDup, SHStrDup.


Document/Contents version 1.00
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com